home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / ams__l~1.zoo / man / sprite.man < prev    next >
Encoding:
Text File  |  1993-09-05  |  5.3 KB  |  185 lines
  1.                         ATARI MACHINE SPECIFIC LIBRARY
  2.  
  3.  
  4.  
  5. NAME
  6.      Sprite - small, high-speed graphic objects
  7.  
  8. SYNOPSIS
  9.      #include <Sprite.h>
  10.  
  11.      class Sprite
  12.      class Incarnation, and derivatives
  13.  
  14. DESCRIPTION
  15.      Many real-time games and other graphical programs are highly
  16.      machine specific, directly accessing the screen memory for the
  17.      highest efficiency.  Routines to rapidly display small graphical
  18.      objects are fundamental to such programs.
  19.  
  20. CLASSES
  21.      Sprites have position (x,y), and shape (an index into a list of
  22.      Incarnations).  They can be drawn, wiped, moved and reshaped.
  23.  
  24.      Incarnations are positionless images that can be drawn and wiped.
  25.      They come in many forms, each tuned to give certain qualities
  26.      as efficiently as possible:
  27.  
  28.      class MonochromeIncarnation
  29.        16 pixels wide (any height), monochrome image (For STHigh and TTHigh).
  30.  
  31.      class PreshiftedMonochromeIncarnation
  32.        16 pixels wide, Faster than regular images, but use 32x memory.
  33.  
  34.      class WideMonochromeIncarnation
  35.        32 pixels wide, monochrome image.
  36.  
  37.      class ColourIncarnation
  38.        16 pixels wide, 16 colour (for STLow and TTMedium).
  39.  
  40.      class PreshiftedColourIncarnation
  41.        16 pixels wide, Faster than regular colour sprites.
  42.  
  43.      class WideColourIncarnation
  44.        32 pixels wide.
  45.  
  46.      All derived incarnations support images of any height.
  47.  
  48. CLASS MEMBERS
  49.   Sprite::
  50.      Sprite(Incarnation *OnlyOne)
  51.         A sprite with one shape.
  52.  
  53.      Sprite(Incarnation **ListOfThem,int Count)
  54.         A sprite with more than one shape.
  55.  
  56.      Sprite(short maxinca)
  57.         A sprite with a list of (initially undefined) shapes.
  58.  
  59.      Sprite(Sprite& Copy)
  60.         A sprite sharing the shapes of another sprite.
  61.  
  62.      Sprite(const char *filename)
  63.         A sprite from a file.
  64.  
  65.      Sprite(FILE *)
  66.         A sprite from a file descriptor.
  67.  
  68.      int Load(const char *filename)
  69.      int Save(const char *filename)
  70.         File I/O
  71.  
  72.      int fput(FILE *)
  73.      int fget(FILE *)
  74.         File descriptor I/O 
  75.  
  76.      void Draw()
  77.        Draw on current page
  78.  
  79.      int TouchDraw()
  80.        [not implemented]
  81.        Draw on the current page, testing for direct image collision
  82.  
  83.      void Wipe()
  84.        Remove from page.  If already wiped, does nothing.
  85.  
  86.      void ShapeTo(short)
  87.        Change incarnation in use.  0 = first incarnation.
  88.  
  89.      int Shape()
  90.        Returns current shape
  91.  
  92.      void Scale(short s)
  93.        Scale of pixels to coordinates.  Coord = 2**Scale * Pixel
  94.        All values below are scaled by this amount
  95.  
  96.      int X()
  97.      int Y()
  98.        Current position (scaled)
  99.  
  100.      int Width()
  101.      int Height()
  102.        Dimensions of current shape (scaled)
  103.  
  104.      void MoveTo(int x, int y)
  105.      void MoveBy(int x, int y)
  106.        Movement (scaled)
  107.  
  108.      void SetImage(int i, Incarnation* In)
  109.        Set one of the possible shapes to a given Incarnation
  110.  
  111.   Incarnation::
  112.      void SetHotSpot(short x, short y)
  113.        Set the centre of the sprite for display purposes.
  114.  
  115.      virtual void    GetImage(Screen&, int x, int y)=0;
  116.        Take the area at (x,y) on the given screen as the image.
  117.        x must be multiple of 16.
  118.  
  119.      [Other Incarnation routines are mainly for use by Sprite]
  120.  
  121.      virtual int fput(FILE *fp)
  122.        Output to file descriptor
  123.  
  124.      virtual void Draw(short x, short y, long *Store)
  125.      virtual int TouchDraw(short x, short y, long *Store) [unimplemented]
  126.        Draw image on double buffer page, saving image covered into
  127.        the area of memory defined by Store.  Coordinates are in pixels.
  128.  
  129.      virtual void Wipe(long *Store)
  130.        Wipe the image from the double buffer page, by using image saved
  131.        in the area of memory defined by Store.
  132.  
  133.      short Width()
  134.      short Height()
  135.        Return width and height of the incarnation.
  136.        Width is actual pixel width from the left.
  137.  
  138.      int BackingRequired()
  139.        Number of words of backing store used by the incarnation.
  140.  
  141. USAGE
  142.      1. Create the sprite, with some incarnations.
  143.      2. Wipe and Draw it in a double-buffering loop (see DoubleBuffer)
  144.  
  145. EXAMPLES
  146.      A simple sprite:
  147.  
  148.      Screen images("foopic.pi1");
  149.      ColourIncarnation fooinca(16);
  150.      fooinca.GetImage(images,0,0);
  151.      Sprite foo(fooinca);
  152.  
  153.      Or, use the EasySprite module.
  154.  
  155. FILES
  156.      Files are saved in the format:
  157.         Sprite-state { Incarnation-type Incarnation-specific-data }
  158.      The details of the format can be cleaned from the source code, but
  159.      generally a programmer should use normal picture files as a medium
  160.      of exchange with foreign routines.
  161.  
  162. SEE ALSO
  163.      EasySprite, MobileSprite, DoubleBuffer
  164.  
  165. DIAGNOSTICS
  166.      Sprites are NOT checked for any bounds exceptions.  The shape
  167.      may be set to a value for which no image is defined, the sprite
  168.      may be drawn off-screen.  These exceptions will usually cause 
  169.      a crash, so be careful - or use/develop higher level modules.
  170.  
  171. AUTHOR
  172.      Warwick Allison, 1992.
  173.      warwick@cs.uq.oz.au
  174.  
  175. COPYING
  176.      This functionality is part of the Atari Machine Specific Library,
  177.      and is Copyright 1992 by Warwick W. Allison.
  178.  
  179.      The Atari Machine Specific Library is free and protected under the
  180.      GNU Library General Public License.
  181.  
  182.      You are free to copy and modify these sources, provided you acknowledge
  183.      the origin by retaining this notice, and adhere to the conditions
  184.      described in the GNU LGPL.
  185.